Aminet 5/Aminet 5 - March 1995.iso/Aminet/util/cli/FInf1_155.lha/FInf/finf.man

Text File | 1994-10-19 | 16KB | 476 lines

File INFo manual
================

File INFo V1.155         by Peter Struijk ([e-mail])

Introduction
------------

FInf is a very versatile directory listing utility.  It can examine the
contents of files and display a short type description.  In addition to this,
FInf has a whole slew of options that allow you to filter files by type, date,
age, size etc., as well as recursive directory descending, and adjustable
output formatting.  So next to simply listing directories, FInf is extremely
useful for creating hybrid commands that perform functions closely tuned to
your specific needs.



Command Line Arguments
----------------------

Usage: FInf [dir/...] [-lf=LFORMAT ["%s"]/...] [-nl=NOLINE [prefix]]
  [EXE] [IMP] [DOC] [IFF] [NOI] [-t=TYPE string] [-nt=NOTYPE]
  [-na=NOANSI] [-nh=NOHEAD] [-ho=HEADONLY] [NEWER[EQ] object]
  [OLDER[EQ] object] [MINUS n timeunit] [PLUS n timeunit] [-aq]
  [-d=DIRS] [-f=FILES] [-q=QUICK] [-p=PATH] [-a=ALL] [NOX] [NOC]
  [BLOCK(S)] [DATES] [-lt=LONGTYPE] [SUB string] [SORT] [BATCH]
  [LARGER size] [SMALLER size] [SINCE [n] date] [UPTO [n] date]

Arguments surrounded by double-quotes are NOT recognized as keywords, this, or
the use of -?  shortcuts can help you circumvent problems with identically
named files and keywords.  Keywords/switches are case independent.

FInf parses its arguments in a left to right order, which may cause keywords
to be overridden by keywords that occur later in the command line.  E.g.
"FInf -nt doc" displays only text files while "FInf doc -nt" will disable file
type checking.

Strings or values belonging to a keyword have to be placed directly after this
keyword.  Unexpected strings are assumed to be file- or directory patterns.
This means you can place patterns or keywords anywhere on the command line,
except after keywords expecting a string.  Upto 32 patterns may be specified.

You may use the backslash "\" as a fixed escape character; If you enter \n it
will be replaced by a new-line, while \" implements a double-quote.

FInf sets a returncode level of 20 (FAIL) on a serious error.
Other returncodes FInf currently sets are:
        0 (OK)    when all went fine.
        5 (WARN)  when no objects (files/dirs) were listed at all.
        7 (WARN)  when a explicitly named object belonging to a keyword was not found.
       10 (ERROR) when a break signal was received.

Examples
--------

In order to get you started, I'll start with a few examples.  A complete
option reference is given later on.

Typing "FInf" without any options will display the files in the current
directory, e.g.

EM                         14228 --p-rwed 12-Jul-90 22:47:39 XLIB IMP
TeX                       130344 ----rwed 04-Feb-90 19:29:42 EXECUTABLE
Introduction                1918 ----rwed 21-Jul-90 15:23:12 ASCII TEXT
Read Me                     1532 ----rwed 22-Jul-90 16:31:52 ASCII TEXT
Graph                       4526 ----rwed 01-Jun-90 18:13:47 IFF PIC
Tmp  (dir)
5 files - 1 directory - 307 blocks - 152548 bytes

Typing "FInf doc" will display all text files in the current directory, and
"FInf disk* exe" will show all executables starting with "disk".

If you use a shell that supports unnamed pipes and aliases, you can very
easily construct new commands as shown below.  If you do not have unnamed
pipes, you can use the BATCH option, the PIPE:  device or temporary files to
obtain equivalent though less elegant functionality.

The BATCH option will cause FInf to output to a temporary file and execute the
contents like a batchfile once it's done.  This will give you the same
functionality as single level unnamed pipes.

------
E=FInf [] noi doc path files lformat " \"%s\"" noline ED | execute
or
E=FInf [] noi doc path files lformat " \"%s\"" noline ED batch

This alias will execute the command ED with a list of text files that match
any wildcards you specify.  Typing "E" while in the directory shown above
would have executed the command `Ed "Introduction" "Read Me"'.  Note how
escaping the quote character allows you to put quotes around the produced
filename, thus avoiding problems with filenames that have spaces in them.

Do not be deterred by the numerous parameters.  Aliases need to be constructed
only once, and when you are examining the requirements of a new alias, you'll
almost automatically conclude you're in need of certain options.  Chances are
FInf provides them.

------
find=FInf NOTYPE FILES QUICK NOHEAD NOANSI PATH ALL SUB []

or abbreviated:

find=FInf -nt -f -q -nh -na -p -a SUB []

This alias will search your current directory, and all subdirectories for
filenames that contain a string you specify.  You can search any directory by
specifying a directory name *after* the search string.  Very useful for
finding files on your harddrive.  If a matching file is found, the full path
will be displayed.


------
FInf *.c Quick Path All | Zoo aI <archive>

The I option in Zoo causes it to read filenames from the standard input, and
these are provided by FInf.  This particular example will archive all C source
files in the current directory and its subdirectories.

------
A good general alias proved to be
FIB=FInf -q -nh -na -aq -p []

Some other examples (for WShell) include (to test omit the BATCH keyword):

alias readme    LITERAL finf -aq sort noi doc "[]#?read#?" -lf "lg %s" batch
alias doc       LITERAL finf -aq sort noi doc "[]#?(.doc|.man)#?" -lf "lg %s" batch
alias guide     LITERAL finf -aq sort noi doc "[]#?.guide#?" -lf "amigaguide %s" batch
alias seek    LITERAL finf -nt noi -f -q -nh -na -p -a SUB []

Example entries for your crontab (Cybercron):

#   Throw away old garbage in trashcan(s)
0    0    *    *    *    FInf WORK:Trashcan REST:Trashcan POOL:Trashcan -p -q -na -nh -lf "*"Delete %s quiet force all*"" UPTO 1 MONTH BATCH
#   Compress manual files
#0    0    *    *    *    FInf MAN: -a -p -q -na -nh -f -aq doc larger 4k -lf "*"XPack >nil: %s method NUKE QUIET*"" BATCH
#   Compress music modules
0    0    *    *    *    FInf MODS: -a -p -q -na -nh -f -aq larger 32k -lf "*"XPack >nil: %s method SQSH QUIET*"" BATCH



File Type Filtering Options
---------------------------

FInf has a set of command line switches that causes it to display only
specific file types.  Here's a list:


-t=TYPE <string>

When FInf recognizes a file, it is able to print a string describing its type.
The TYPE option allows you to display only those files where the pattern
<string> occurs in this file type description.  This keyword can be used to
select virtuallly any file type or groups of file types just by supplying a
carefully chosen <string>.  Note that the LONGTYPE option causes FInf to
search the extended file type description instead of searching the short
description.

List of currently recognized file types:

The following list can be generated by "FInf ?" followed by another "?" at the
":" prompt.  FInf's file type recognition is not by any means complete and
even a bit outdated but serves well to distinguish between major groups of
files like e.g.  executables, text, iff.

SHORT         LONG

UNREADABLE    "Unable to read"
UNKNOWN       "Unknown type"
FIMP DATA     "FImp data file"
OBJ CODE      "Linkable object code"
TTW PIC       "TTW picture"
PW DATA       "PowerWindows data"
DIMP DATA     "DImp data file"
IFF PIC       "IFF picture"
IFF SOUND     "IFF sound"
IFF SCORE     "IFF score"
IFF TEXT      "IFF text"
IFF DMS       "IFF Deluxe Music score"
IFF ANI       "IFF animation"
IFF S3D       "IFF Sculpt 3D scene"
IFF DLV       "IFF Deluxe Video"
IFF DOC       "IFF document"
IFF FILE      "IFF data file"
ASCII TEXT    "ASCII Text"
OLD IMP       "Old imploded"
NORM IMP      "Normal imploded"
PURE IMP      "Pure imploded"
OVLY IMP      "Overlayed imploded"
XLIB IMP      "Library imploded"
XLIB IMP!     "Short library imploded"
EXECUTABLE    "Executable"
OVERLAYED     "Overlayed executable"
NORM IMP*     "Protected normal imploded"
PURE IMP*     "Protected pure imploded"
OVLY IMP*     "Protected overlayed imploded"
XLIB IMP*     "Protected library imploded"
FONT HDR      "Font header"
WB ICON       "WB icon"
DISK ICON     "WB disk icon"
DRAWER        "WB drawer icon"
TOOL          "WB tool icon"
PROJECT       "WB project icon"
GARBAGE       "WB garbage icon"
DEVS ICON     "WB device icon"
KICK ICON     "WB kick icon"


In addition to filtering file types with the TYPE option there are a number of
often used types that may be directly specified by keyword.  These are:

EXE - Display executable files (except imploded executables).
IMP - Display imploded files and imploded data files.
DOC - Display ASCII text files.
IFF - Display all kinds of IFF files. You may also use the TYPE keyword
      to accomplish further differentation.



Other Filtering Options
-----------------------

In addition to type filtering, FInf can also examine other properties with
which to exempt certain files from being displayed:


NEWEREQ <object>

Display only objects which were created after or at the same time as
<object>.


NEWER <object>

Display only objects which were created after <object>.

OLDEREQ <object>

Display only objects which were created before or at the same time
as <object>.


OLDER <object>

Display only objects which were created before <object>.


UPTO [n] <date>

Display only those objects created UPTO a specified date. UPTO accepts
three formats:
    DD-MMM-YY
    TODAY/YESTERDAY/TOMORROW/MONDAY...SUNDAY/FUTURE
    [n] TICK(S)/SECOND(S)/MINUTE(S)/HOUR(S)/DAY(S)/WEEK(S)/MONTH(S)/YEAR(S)
The integer [n] is optional, default is 1. The latter option is
very handy to cleanup your news directory.
E.g. FInf NEWS: -a -p -lf "Delete %s" UPTO 8 WEEKS BATCH
Make sure your system clock contains the correct time! :-)


SINCE [n] <date>

Display only objects since a specified date. For information on the date
formats see UPTO.


MINUS <n> <timeunit>

Substracts a (fixed) offset from the (run-time) date and time specified by
any SINCE, UPTO, NEWER[EQ] and OLDER[EQ] keywords. The time format is a subset
of the format supported by the SINCE and UPTO keywords:
    <n> TICK(S)/SECOND(S)/MINUTE(S)/HOUR(S)/DAY(S)/WEEK(S)/MONTH(S)/YEAR(S)
The integer <n> is required.
E.g. FInf NEWS: -a -p -lf "Delete %s" OLDER .lastread MINUS 3 days
This deletes all files 3 days older than the date of the .lastread file.


PLUS <n> <timeunit>

Adds a (fixed) offset to the (run-time) date and time specified by any SINCE,
UPTO, NEWER[EQ] and OLDER[EQ] keywords. See MINUS for the time offset format.


LARGER <integer>

Display only files with a size larger than or equal to <integer> bytes.
You can specify kilobytes by adding a 'k' as in:
FInf #? ALL LARGER 100K


SMALLER <integer>

Display only files with a size smaller than or equal to <integer> bytes.
You can specify kilobytes by adding a 'k' as in:
FInf #? SMALLER 10K


SUB <string>

Display only objects containing at least one occurance of <string> in their
objectname.


NOI

Do not display .info files.


-d=DIRS

Display directories only.


-f=FILES

Display only files.


-a=ALL

Recursively displays the contents of any subdirectories in addition to
the files/dirs in the current directory.  Wildcards in the path description
are not supported (yet), so for now this option will cause FInf to
recursively enter ALL encountered directories.



Formatting Options
------------------

These switches and keywords control the way in which FInf generates its
output:


BATCH

This will capture FInf's output into a uniquely named temporary file in the T:
directory, and subsequently will execute the file as a batch file that will be
deleted after completion.  This option is handy if you don't have unnamed
pipes.


BLOCK=BLOCKS

This switch will cause FInf to display the number of blocks files occupy on
disk instead of their lengths.  Note that for devices using the fast filing
system, this value will include any extension blocks.


DATES

This will cause FInf to print absolute dates instead of dates with "Yesterday"
of "Sunday" in them.


-lt=LONGTYPE

If specified, FInf will generate listings with a more verbose type
description.  In order to create printing space for this, the date and
protection flags will not be displayed.


-nt=NOTYPE

If you use this switch, the contents of files will not be examined.  The type
description will therefore not be displayed.  The EXE, IMP, DOC, IFF etc.
filters won't work if NOTYPE is set.  NOTYPE will cause FInf to operate about
twice as fast because of the decreased amount of work it has to do for each
file.


-na=NOANSI

This surpresses the generation of ANSI codes used by FInf to select bold or
italic font styles in the footer and such.


-nh=NOHEAD

Like with the normal List command, NoHead will stop FInf from generating
headers/footers with additional information on the examined files.


-ho=HEADONLY

This option is included to quickly simulate the unix DU command.  DU stands
for Directory Usage, an example alias:  du = finf -ho -a []


NOX

This option removes extensions from the filenames.  This might be handy when
you only wish to pass the filename root into the LFormat output.  E.g.  FInf
*.twiddle NOX LFormat "Rename %s.twiddle %s.twaddle" | execute changes all
.twiddle extensions into .twaddle extensions.


NOC

This simple option tells FInf to NOT print any filenotes (comments) which
might be attached to a file or directory.  Note that when the QUICK option is
in effect filenotes are already been ignored.


-q=QUICK

In quick mode, FInf will display only filenames and any paths.  No lengths,
flags, dates, comments or types will be printed, the type filter switches will
still function though.  These bare (path+)file names can be more readily used
by programs you intend to feed FInf's output to.


-p=PATH

If set, a full path will be pasted in front of any displayed filenames.  This
option is useful e.g.  in conjunction with the LFormat or ALL switches.


-lf=LFORMAT <"...%s...%s...">

Works like List's LFormat option.  Briefly, you can specify a string with a
"%s" in it (up to 8 %s expansions are supported), and where FInf normally
would have printed paths+file names, it displays the given string with the
path + file at the %s location.  Useful for pasting commands in front of
filenames so you can pipe the output of FInf to a batchfile, or directly to
execute (if your shell supports this).  E.g.  FInf LFORMAT "rename \"%s\"
\"%s.doc\"" FILES DOC BATCH will append a ".doc" extension to all ASCII files
found.


-nl=NOLINE [prefix]

This causes FInf not to print linefeeds between filenames.  If you use this
together with a LFormat " %s" and a QUICK switch, you'll get a line with file
names separated by spaces.  In the prefix position you may optionally specify
a string to be pasted in front of this line.  This will probably be the name
of a command which requires a list of filenames as its parameters.  Note that
this line will only be printed if any filenames matching your wildcard
specification were found.  E.g.  FInf NOLINE "Ed " LFORMAT "\"%s\" " PATH
FILES will produce something like:  Ed "ram:file1" "ram:doc1" "ram:readme"


SORT

At last, this one sorts the filenames before printing. It didn't require
a rewrite BUT only because this option also enables the NOANSI, NOHEADER
and QUICK keywords. (-na -nh -q), making it less useful for normal
interactive usage. It's primary intended for BATCH jobs.


-aq

This stands for AddQuotes and does just that, it places quotes (") around
all object names. This saves some problems with escaping "'s in aliasses
or simplifies complicated one liners...


General Information
-------------------

This program is Freely-Distributable, as opposed to Public Domain.  Permission
is given to freely distribute this program provided you include this
documentation and any other related files, and no fee is charged in excess of
reasonable media and mailing costs.

Currently FInf supports the #,?  and * wild cards.  OS 2.0 wildcarding is used
automatically.  If, during normal operation, there is only one file matching
the file/wildcard specification, and if it is a program file, some additional
information about the number of hunks and the memory usage will be displayed.

FInf is pure and can be made resident.

Peter Struijk
([e-mail])